---
title: Capture Plugin
description: Enables users to select a rectangular area on a page and export it as an image snapshot.
searchable: true
---

# Capture Plugin

The Capture Plugin provides a "snapshot" tool, allowing users to select a rectangular area (a marquee) on any page and export that specific section as a high-resolution image.

## Installation

This plugin depends on the `Render` and `Interaction Manager` plugins. You must install all three packages.

```sh npm2yarn
npm install @embedpdf/plugin-capture @embedpdf/plugin-render @embedpdf/plugin-interaction-manager
````

## Registration

Import `CapturePluginPackage` and its dependencies, then add them to the `plugins` array. The dependencies should be registered before the capture plugin.

```tsx {6, 19-23}
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/react'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/react'
import { CapturePluginPackage } from '@embedpdf/plugin-capture/react'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),

  // Register dependencies first
  createPluginRegistration(RenderPluginPackage),
  createPluginRegistration(InteractionManagerPluginPackage),

  // Register and configure the capture plugin
  createPluginRegistration(CapturePluginPackage, {
    scale: 2.0, // Render captured image at 2x resolution
    imageType: 'image/png',
    withAnnotations: true,
  }),
]
```

## Usage

The plugin works by combining a UI component to draw the selection area, a hook to control the capture mode, and an event listener to handle the final image.

### 1\. Add the `<MarqueeCapture />` Component

To enable the visual selection tool, place the `<MarqueeCapture />` component inside the `renderPage` prop of your `<Scroller />`. It must be a child of `<PagePointerProvider>` to correctly handle mouse or touch interactions.

```tsx {2, 9}
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/react';
import { MarqueeCapture } from '@embedpdf/plugin-capture/react';

// ...
<Scroller
  renderPage={({ width, height, pageIndex, scale, rotation }) => (
    <PagePointerProvider {...{ pageIndex, width, height, scale, rotation }}>
      <RenderLayer pageIndex={pageIndex} />
      <MarqueeCapture pageIndex={pageIndex} scale={scale} />
    </PagePointerProvider>
  )}
/>
```

### 2\. Build a Toolbar Button

Use the `useCaptureCapability` hook to get access to the plugin's methods. The `toggleMarqueeCapture()` method activates and deactivates the selection mode.

```tsx
import { useCaptureCapability } from '@embedpdf/plugin-capture/react';

const CaptureToolbar = () => {
  const { provides: capture } = useCaptureCapability();
  const isActive = capture?.isMarqueeCaptureActive();

  return (
    <button onClick={() => capture?.toggleMarqueeCapture()}>
      {isActive ? 'Cancel' : 'Capture Area'}
    </button>
  );
}
```

### 3\. Handle the Captured Image

After the user selects an area, the plugin fires an event with the resulting image data. You must listen for this event using the `onCaptureArea` method to receive the `Blob`. From there, you can display the image or trigger a download.

```tsx
import { useEffect, useState } from 'react';
import { useCaptureCapability, CaptureAreaEvent } from '@embedpdf/plugin-capture/react';

const CaptureResult = () => {
  const { provides: capture } = useCaptureCapability();
  const [imageUrl, setImageUrl] = useState<string | null>(null);

  useEffect(() => {
    if (!capture) return;

    const unsubscribe = capture.onCaptureArea((result: CaptureAreaEvent) => {
      const newUrl = URL.createObjectURL(result.blob);
      setImageUrl(newUrl);
    });

    return () => {
      unsubscribe();
      if (imageUrl) URL.revokeObjectURL(imageUrl);
    };
  }, [capture]);

  if (!imageUrl) return <p>Select an area to capture.</p>;

  return <img src={imageUrl} alt="Captured PDF area" />;
};
```

## Live Example

Click the "Capture Area" button, then click and drag a rectangle over the PDF. The selected area will appear below as an image, with a button to download it.

import { PDFViewer } from '../code-examples/capture-example';

<PDFViewer />

## API Reference

### Configuration (`CapturePluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`scale`** | `number` | The resolution multiplier for the captured image. A value of `2` means 2x resolution. **Default**: `1` |
| **`imageType`** | `string` | The image format, e.g., `'image/png'`, `'image/jpeg'`. **Default**: `'image/png'` |
| **`withAnnotations`** | `boolean` | If `true`, annotations will be included in the captured image. **Default**: `false` |

### Component: `<MarqueeCapture />`

The component that renders the visual selection rectangle.

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | **(Required)** The page index this component is rendered on. |
| **`scale`** | `number` | **(Required)** The current scale of the page. |
| **`className`** | `string` | Optional CSS class for custom styling of the marquee. |
| **`stroke`** | `string` | The color of the marquee's border. |
| **`fill`** | `string` | The background color of the marquee. |

### Hook: `useCaptureCapability()`

Connects your component to the capture plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`**| `CaptureCapability \| null` | An object with methods to interact with the plugin, or `null` if not ready. |

#### `CaptureCapability` Methods

| Method | Description |
| :--- | :--- |
| **`toggleMarqueeCapture()`** | Toggles the marquee selection mode on or off. |
| **`isMarqueeCaptureActive()`**| Returns `true` if the marquee selection mode is currently active. |
| **`onCaptureArea(callback)`** | Subscribes to the capture event. The callback receives a `CaptureAreaEvent` object when an area is successfully captured. |
| **`captureArea(pageIndex, rect)`** | Programmatically captures a specified rectangular area on a page. |

### Event: `CaptureAreaEvent`

The object passed to the `onCaptureArea` callback after a successful capture.

| Property | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | The index of the page where the capture occurred. |
| **`rect`** | `Rect` | An object describing the position and size of the captured area in PDF points. |
| **`blob`** | `Blob` | The captured image data as a `Blob` object. |
| **`imageType`** | `string` | The MIME type of the captured image (e.g., `'image/png'`). |
| **`scale`** | `number` | The resolution scale factor used for the capture. |
